Skip to content

Comments

feat: add reference repos integration and update planning docs#13

Merged
phroi merged 3 commits intomasterfrom
feat/reference-repos
Feb 17, 2026
Merged

feat: add reference repos integration and update planning docs#13
phroi merged 3 commits intomasterfrom
feat/reference-repos

Conversation

@phroi
Copy link
Member

@phroi phroi commented Feb 17, 2026

Why

Adds ability to clone and reference the ickb-contracts and ickb-whitepaper repositories for local development context. Updates planning documentation to reflect enhanced architecture understanding from contract and whitepaper analysis.

Changes

  • Add pnpm reference command to clone contracts and whitepaper repos
  • Update .gitignore to exclude reference directories
  • Enrich planning docs (ARCHITECTURE, STRUCTURE, CONCERNS, etc.) with contract and whitepaper context
  • Document that gh CLI is unavailable, use pnpm pr/pnpm review instead
  • Add README section explaining reference repository integration

phroi and others added 3 commits February 17, 2026 02:38
Enables Claude to read the on-chain Rust contracts and protocol
whitepaper on demand for better context about the iCKB protocol.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add protocol design, on-chain contract architecture, validation rules,
error codes, Molecule schemas, and TS-Rust alignment concerns derived
from the contracts and whitepaper reference repos.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@gemini-code-assist
Copy link

Summary of Changes

Hello @phroi, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the development environment by integrating external reference repositories for on-chain contracts and protocol documentation directly into the local workspace. This integration provides immediate access to critical architectural and implementation details, which has been used to comprehensively update and enrich the project's planning documentation. The changes aim to improve developer understanding and streamline the development process by centralizing relevant information and clarifying tooling usage.

Highlights

  • Reference Repository Integration: Introduced a new pnpm reference command to clone the ickb-contracts (Rust L1 scripts) and ickb-whitepaper (protocol design) repositories into the project root. These repositories are git-ignored and set to read-only, providing local context for development and AI tooling.
  • Enhanced Planning Documentation: Significantly updated and expanded the codebase planning documents (ARCHITECTURE.md, CONCERNS.md, CONVENTIONS.md, INTEGRATIONS.md, STACK.md, STRUCTURE.md) with detailed information derived from the newly integrated reference repositories. This includes in-depth protocol design, contract specifics, and refined codebase structure.
  • Developer Tooling Clarification: Documented the unavailability of the gh CLI and reinforced the use of pnpm pr and pnpm review for GitHub Pull Request interactions, ensuring developers use the intended workflow.
  • Git Ignore Updates: Modified the .gitignore file to exclude the newly cloned contracts/ and whitepaper/ reference directories, preventing them from being committed to the main repository.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • .gitignore
    • Added entries for 'contracts/' and 'whitepaper/' to exclude reference repositories from version control.
  • .planning/codebase/ARCHITECTURE.md
    • Updated analysis date.
    • Expanded pattern overview, protocol design, on-chain contracts, layers, data flow, key abstractions, entry points, error handling, and cross-cutting concerns sections with detailed information.
  • .planning/codebase/CONCERNS.md
    • Updated analysis date.
    • Marked the 'Local Epoch Class Partially Duplicates CCC Upstream' concern as resolved.
    • Adjusted line numbers for UDT handling references.
    • Added new concerns regarding 'TS Exchange Rate Must Match Rust Contract Logic' and 'TS Molecule Codecs Must Match Contract Schemas' under testing priorities.
  • .planning/codebase/CONVENTIONS.md
    • Updated analysis date.
    • Added a 'Tooling' section clarifying gh CLI usage and recommending pnpm pr/pnpm review.
    • Removed 'epoch.ts' from the list of single lowercase word files.
    • Updated Molecule/Codec patterns to align with ccc.Entity.Base and @ccc.codec and emphasized matching TS codecs to Molecule schema.
    • Removed the note about Epoch private constructors.
  • .planning/codebase/INTEGRATIONS.md
    • Updated analysis date.
    • Significantly expanded the 'Smart Contracts (On-Chain Scripts)' section with detailed descriptions, validation rules, data formats, error codes, and Molecule schema for each contract (NervosDAO, iCKB UDT, iCKB Logic, Owned Owner, Order).
  • .planning/codebase/STACK.md
    • Updated analysis date.
    • Added a new 'On-Chain (reference)' section under 'Languages' to describe Rust contracts.
    • Updated the note on CCC upstream contributions to reflect the resolution of the local Epoch class duplication.
  • .planning/codebase/STRUCTURE.md
    • Updated analysis date.
    • Expanded the directory layout and purposes with granular details for packages, apps, and new reference directories (contracts/, whitepaper/).
    • Refined key file locations, naming conventions, and guidance on where to add new code.
    • Updated the description of the ccc-dev/ special directory and added contracts/ and whitepaper/ as new special directories.
  • .planning/codebase/TESTING.md
    • Updated analysis date.
    • Removed 'epoch.ts' from the list of files for unit testing targets.
    • Added a new 'Contract-Alignment Tests' section, detailing critical cross-language validation tests for exchange rates, Molecule encoding, and order logic.
  • README.md
    • Added a new 'Reference' section explaining how to clone contracts and whitepaper repositories.
    • Added a note under 'Developer Scripts' about gh CLI unavailability and recommending pnpm pr/pnpm review.
  • package.json
    • Added new reference, reference:contracts, and reference:whitepaper scripts to facilitate cloning and setting permissions for reference repositories.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a pnpm reference command to clone the ickb-contracts and ickb-whitepaper repositories, providing valuable local context for development. The associated updates to .gitignore and package.json are correct. The bulk of the changes consists of extensive and high-quality updates to the planning documentation, integrating insights from the contract and whitepaper analysis. These documentation improvements are excellent and will be very helpful for the team. I've made one suggestion in package.json to improve script robustness by using && instead of ;. There's a minor discrepancy in the pull request description, which states that the repositories are cloned into a .reference/ directory, whereas the implementation uses contracts/ and whitepaper/. This seems to be just a small inconsistency in the description, as the code and .gitignore are consistent with the latter.

@phroi
Copy link
Member Author

phroi commented Feb 17, 2026

LGTM

Phroi %31

@phroi phroi merged commit 978c849 into master Feb 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant